XML PARSE

isCOBOL Evolve : Language Reference : Procedure Division Statements : XML PARSE

XML PARSE

The XML PARSE statement parses an XML document into its individual pieces and passes each piece, one at a time, to a user-written processing procedure.

General Format

XML PARSE Xml-Stream

[ WITH ENCODING Code-page ]

[ VALIDATING WITH { Identifier-1 } ]

{ FILE Schema-1 }

PROCESSING PROCEDURE IS Procedure-Name-1

[ { THROUGH } Procedure-Name-2 ]

{ THRU }

[ ON EXCEPTION Imperative-Statement-1 ]

[ NOT ON EXCEPTION Imperative-Statement-2 ]

[END-XML]

Syntax Rules

1. Xml-Stream must reference an elementary data item of category alphanumeric, an alphanumeric group item or an elementary data item of category national. If it references an alphanumeric group item, then it is treated as though it were an elementary data item of category alphanumeric.

2. Code-page must be numeric data item or literal.

3. Identifier-1 is an alphanumeric data item.

4. Schema-1 must be defined in the XML-SCHEMA clause of the SPECIAL-NAMES paragraph.

5. Procedure-Name-1 is the first or only section or paragraph in the processing procedure.

6. Procedure-Name-2 is the last section or paragraph in the processing procedure.

General Rules

1. If specified, Code-page indicates the encoding used in the XML stream; possible values are:

Code-page	Encoding
37 273 277 278 280 284 285 290 297 300 420 424 437 500 775 813 819 833 834 850 852 855 857 858 860 861 862 863 864 865 866 868 869 870 871 874 875 912 914 915 916 918 920 921 922 930 932 933 935 936 937 939 942 943 948 949	IBM037 IBM273 IBM277 IBM278 IBM280 IBM284 IBM285 IBM290 IBM297 x-IBM300 IBM420 IBM424 IBM437 IBM500 IBM775 ISO-8859-7 ISO-8859-1 x-IBM833 x-IBM834 IBM850 IBM852 IBM855 IBM857 IBM00858 IBM860 IBM861 IBM862 IBM863 IBM864 IBM865 IBM866 IBM868 IBM869 IBM870 IBM871 x-IBM874 x-IBM875 ISO-8859-2 ISO-8859-4 ISO-8859-5 ISO-8859-8 IBM918 ISO-8859-8 x-IBM921 x-IBM922 x-IBM930 x-MS932_0213 x-IBM933 x-IBM935 x-mswin-936 x-IBM937 x-IBM939 x-IBM942 x-IBM943 x-IBM948 x-IBM949
950 964 970 1025 1026 1046 1097 1098 1112 1122 1123 1124 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1166 1200 1208 1250 1251 1252 1253 1254 1255 1256 1257 1258 1364 1381 1383 33722 62210 62222 62238	x-IBM950 x-IBM964 x-IBM970 x-IBM1025 IBM1026 x-IBM1046 x-IBM1097 x-IBM1098 x-IBM1112 x-IBM1122 x-IBM1123 x-IBM1124 IBM01140 IBM01141 IBM01142 IBM01143 IBM01144 IBM01145 IBM01146 IBM01147 IBM01148 IBM01149 x-IBM1166 UTF-16 UTF-8 windows-1250 windows-1251 windows-1252 windows-1253 windows-1254 windows-1255 windows-1256 windows-1257 windows-1258 x-IBM1364 x-IBM1381 x-IBM1383 x-IBM33722 ISO-8859-8 ISO-8859-9 ISO-8859-9

Code-page

Encoding

273

277

278

280

284

285

290

297

300

420

424

437

500

775

813

819

833

834

850

852

855

857

858

860

861

862

863

864

865

866

868

869

870

871

874

875

912

914

915

916

918

920

921

922

930

932

933

935

936

937

939

942

943

948

949

IBM037

IBM273

IBM277

IBM278

IBM280

IBM284

IBM285

IBM290

IBM297

x-IBM300

IBM420

IBM424

IBM437

IBM500

IBM775

ISO-8859-7

ISO-8859-1

x-IBM833

x-IBM834

IBM850

IBM852

IBM855

IBM857

IBM00858

IBM860

IBM861

IBM862

IBM863

IBM864

IBM865

IBM866

IBM868

IBM869

IBM870

IBM871

x-IBM874

x-IBM875

ISO-8859-2

ISO-8859-4

ISO-8859-5

ISO-8859-8

IBM918

ISO-8859-8

x-IBM921

x-IBM922

x-IBM930

x-MS932_0213

x-IBM933

x-IBM935

x-mswin-936

x-IBM937

x-IBM939

x-IBM942

x-IBM943

x-IBM948

x-IBM949

950

964

970

1025

1026

1046

1097

1098

1112

1122

1123

1124

1140

1141

1142

1143

1144

1145

1146

1147

1148

1149

1166

1200

1208

1250

1251

1252

1253

1254

1255

1256

1257

1258

1364

1381

1383

33722

62210

62222

62238

x-IBM950

x-IBM964

x-IBM970

x-IBM1025

IBM1026

x-IBM1046

x-IBM1097

x-IBM1098

x-IBM1112

x-IBM1122

x-IBM1123

x-IBM1124

IBM01140

IBM01141

IBM01142

IBM01143

IBM01144

IBM01145

IBM01146

IBM01147

IBM01148

IBM01149

x-IBM1166

UTF-16

UTF-8

windows-1250

windows-1251

windows-1252

windows-1253

windows-1254

windows-1255

windows-1256

windows-1257

windows-1258

x-IBM1364

x-IBM1381

x-IBM1383

x-IBM33722

ISO-8859-8

ISO-8859-9

2. The VALIDATING phrase specifies that the parser should validate the XML document against an XML schema while parsing it. If the FILE keyword is not specified, Identifier-1 must reference a data item that contains the XML schema. If the FILE keyword is specified, Schema-1 identifies an existing file that contains the XML schema. During parsing with validation, normal XML events are returned as for non-validating parsing until an exception occurs due to a validation error or other error in the document. When an XML document is not valid, the parser signals an XML exception and passes control to the processing procedure with special register XML-EVENT containing 'EXCEPTION' and special-register XML-CODE containing return code 24 in the high-order halfword and a reason code in the low-order halfword.

3. The processing procedure consists of the statements at which XML events are handled. The range of the processing procedure also includes all statements executed by CALL, EXIT, GO TO, GOBACK, and PERFORM statements in the range of the processing procedure.

4. The processing procedure must not directly execute an XML PARSE statement. However, if the processing procedure passes control to another program by using a CALL statement, the target program can execute the same or a different XML PARSE statement. A program executing on multiple threads can execute the same XML statement or different XML statements simultaneously.

5. An exception condition occurs when the XML parser detects an error in processing the XML document. The parser first signals an exception XML event by passing control to the processing procedure with special register XML-EVENT set to contain 'EXCEPTION'. If the XML processing procedure handles the exception XML event and sets XML-CODE to zero before returning control to the parser, the exception condition no longer exists. If no other unhandled exceptions occur prior to the termination of the parser, control is transferred to Imperative-Statement-2 of the NOT ON EXCEPTION phrase, if specified.

6. If an exception condition does not exist at termination of XML PARSE processing, control is transferred to Imperative-Statement-2 if the NOT ON EXCEPTION clause is specified. Otherwise control is transferred to the end of the XML PARSE statement.

Note: Unlike the IBM implementation of XML PARSE, isCOBOL doesn’t return VERSION-INFORMATION and STANDALONE-DECLARATION events.

Examples

Parse a simple XML, display it and use some key data from it

working-storage section.

01 xml-document.

02 pic x(36) value '<?xml version="1.0" encoding="utf-8"'.

02 pic x(19) value ' standalone="yes"?>'.

02 pic x(39) value ''.

02 pic x(10) value '<sandwich>'.

02 pic x(35) value ' <bread type="baker's best"/>'.

02 pic x(41) value ' <?spread please use real mayonnaise ?>'.

02 pic x(31) value ' <meat>Ham & turkey</meat>'.

02 pic x(40) value ' <filling>Cheese, lettuce, tomato, etc.'.

02 pic x(10) value '</filling>'.

02 pic x(35) value ' <![CDATA[We should add a <relish>'.

02 pic x(22) value ' element in future!]]>'.

02 pic x(31) value ' <listprice>$4.99 </listprice>'.

02 pic x(27) value ' <discount>0.10</discount>'.

02 pic x(15) value '</sandwich>'.

01 xml-document-length computational pic 999.

01 my-msg pic x(30).

01 current-element pic x(30).

01 xfr-ed pic x(9) justified.

01 xfr-ed-1 redefines xfr-ed pic 999999.99.

01 list-price computational pic 9v99 value 0.

01 discount computational pic 9v99 value 0.

01 display-price pic $$9.99.

01 prom-price pic $$9.99.

procedure division.

main.

display xml-document

xml parse xml-document processing procedure xml-handler

on exception display 'XML document error ' xml-code x'0d0a' xml-errmsg

not on exception display 'XML document successfully parsed'

end-xml

move list-price to display-price

compute prom-price = list-price * (1 - discount)

display 'Information from XML ' x'0d0a'

' Sandwich list price: ' display-price x'0d0a'

' Promotional price: ' prom-price

end-display

goback.

xml-handler.

evaluate xml-event

when 'DOCUMENT-TYPE-DECLARATION ' display 'Doc type decl: ' XML-TEXT

when 'START-OF-ELEMENT'

display 'Start element tag: <' XML-TEXT '>'

move XML-TEXT to current-element

when 'CONTENT-CHARACTERS'

display 'Content characters: <' XML-TEXT '>'

evaluate current-element

when 'listprice' compute list-price = function numval-c(XML-TEXT)

when 'discount'

move XML-TEXT to xfr-ed

move xfr-ed-1 to discount

end-evaluate

when 'END-OF-ELEMENT'

display 'End element tag: <' XML-TEXT '>'

move spaces to current-element

when 'START-OF-DOCUMENT'

compute xml-document-length = function length(XML-TEXT)

display 'Start of document: length=' xml-document-length

' characters.'

when 'END-OF-DOCUMENT' display 'End of document.'

when 'VERSION-INFORMATION' display 'Version: <' XML-TEXT '>'

when 'ENCODING-DECLARATION' display 'Encoding: <' XML-TEXT '>'

when 'STANDALONE-DECLARATION' display 'Standalone: <' XML-TEXT '>'

when 'ATTRIBUTE-NAME' display 'Attribute name: <' XML-TEXT '>'

when 'ATTRIBUTE-CHARACTERS' display 'Attribute value characters: <' XML-TEXT '>'

when 'ATTRIBUTE-CHARACTER' display 'Attribute value character: <' XML-TEXT '>'

when 'START-OF-CDATA-SECTION' display 'Start of CData: <' XML-TEXT '>'

when 'END-OF-CDATA-SECTION' display 'End of CData: <' XML-TEXT '>'

when 'CONTENT-CHARACTER' display 'Content character: <' XML-TEXT '>'

when 'PROCESSING-INSTRUCTION-TARGET' display 'PI target: <' XML-TEXT '>'

when 'PROCESSING-INSTRUCTION-DATA' display 'PI data: <' XML-TEXT '>'

when 'COMMENT' display 'Comment: <' XML-TEXT '>'

when 'EXCEPTION'

compute xml-document-length =

function length (XML-TEXT)

move XML-TEXT (xml-document-length - 5:10) to my-msg

display 'Exception ' XML-CODE ' at offset '

xml-document-length ':' xml-errmsg ':' my-msg

when other display 'Unexpected XML event: ' XML-EVENT '.'

end-evaluate.